Overview: Why am I here?

Lotus Sametime features are continually evolving, and each Lotus Sametime release introduces new features and fixes. To take advantage of the full unified-collaboration experience, many organizations choose the Lotus Notes embedded Sametime client, instead of maintaining both a Notes client install and a separate Sametime Connect client install. The Lotus Expeditor platform, on which 8.0.x and later versions of both the Notes client (standard configuration) and Sametime Connect client are built, has improved its capabilities in the client upgrade space.

These improvements allow closer feature-and-fix parity between the Sametime embedded and the Sametime Connect standalone client, and they allow administrators to upgrade from versions prior to Notes 8.5.1 clients (8.0.x or earlier) to the Notes 8.5.1 Fix Pack 3 (FP3) client with the Sametime 8.5.x embedded client in either a single or multi-step upgrade.

Intended audience

This article will benefit organizations that:

• Have or are planning to deploy Notes 8.5.1 clients into their production environment
• Use or plan to use the Sametime embedded client in Lotus Notes, rather than a standalone Sametime Connect client
• Would like to upgrade the embedded Sametime client version from 8.0.x to 8.5.x

Topics to be discussed include:

• Planning and deployment considerations; known issues
• Planning and migrating Sametime authentication from a Lotus Domino® Directory to an LDAP format
• Provisioning default Sametime embedded client preferences
• Enabling optional Sametime features
• Using Smart Upgrade to deploy the Notes 8.5.1 FP3 or later client and the Sametime Add-On Installer in one package

Terms and definitions

First, let's clarify several terms that are used repeatedly throughout this article:

• The Lotus Sametime client has two installation models: standalone and embedded. Embedded refers to the Sametime client embedded within the Notes client.
• The term "Sametime client" in this article refers to the embedded Sametime client. Any references to the Sametime Connect standalone client are stated explicitly and appear only for comparative purposes.
• The Lotus Notes 8.5.x client can be updated by use of add-on installers. This article specifically deals with the add-on installer that upgrades the embedded Sametime client. It's important to note, however, that there are add-on installers of many types.
• The terms install and installer refer to an '.exe' or other file that installs a product. Installation refers to one instance of a software product deployment.

Where am I? Where am I going?: Mapping your upgrade path

Administrators must evaluate their current Lotus Notes and Lotus Sametime client installations to plan their upgrade to the Notes 8.5.1 FP3 or later client with the embedded Sametime 8.5.1 or greater client. The Sametime add-on installer can be applied only to version-8.5.1-or-later Notes client installations. Note that to the Sametime 8.5.2 embedded client requires the 8.5.2 Notes client. See Technote #1370003 for more details on supported versions.

If you, the administrator, want to

• upgrade the Notes client and run the Sametime add-on installer in one package, then refer to the Using Smart Upgrade to deploy the Sametime add-on installer section.

• deploy just the Sametime add-on installer with existing 8.5.1 client installations, then refer to the Post-installation deployment section.

NOTE: Using the add-on installer to upgrade the embedded Sametime client marks a strategic shift for future Sametime updates. Notes install packages and Sametime add-on installers containing versions older than the targeted Notes client installation do not affect the embedded Sametime client. Only when a Notes update or install, or Sametime add-on installer containing newer Sametime client code is run, will the Sametime client be upgraded. See figure 1 and the next section for additional details.

Figure 1. Future Sametime updates

What should I know?: Deployment considerations and known issues

Administrators should know that, once the embedded Sametime client is upgraded by use of the Sametime add-on installer, it cannot be downgraded. The Notes client must be uninstalled and then reinstalled with the original Sametime client, and then Sametime can be upgraded to the desired version. The Notes client cannot be uninstalled without uninstalling the Sametime client.

The Sametime client will not be affected by Sametime client code contained in Notes Cumulative Client Hotfixes (CCHs) or other Notes updates, unless they contain later versions of the Sametime client. This means:

• Notes client install versions containing older Sametime versions will NOT downgrade the newer embedded Sametime client when installed over a Notes client with an upgraded embedded Sametime client.

• Notes client install versions containing newer Sametime versions WILL upgrade the embedded Sametime client, when installed over a Notes client with an upgraded, but older, embedded Sametime client.

• Known Issue: The Sametime add-on installer runs only once on Notes 8.5.1 FP1 clients. Therefore FP1 Notes clients should NOT have their embedded Sametime client upgraded by using the Post-installation deployment method. Notes 8.5.1 FP1 installations must be upgraded in conjunction with the FP3 upgrade as described in this article's Using Smart Upgrade to deploy the Sametime add-on installer section.

• The Sametime Advanced add-on installer requires embedded Sametime 8.5.1.

• Installing or uninstalling other add-on installers, such as Sametime Advanced, does NOT affect the Sametime client.

• Migrating users from the standalone Sametime Connect client will not cause loss of Buddy or Privacy lists, but local user preferences will not be migrated to the embedded Sametime client installation.

What should I do?: Planning the upgrade

Administrators must convert Sametime authentication from Domino to LDAP as required by Sametime 8.5.1. Beginning in release 8.5, Lotus Sametime requires the use of an LDAP directory for user authentication. Rather than installing a new LDAP directory, you can convert your existing Lotus Domino Directory to LDAP format when migrating your Sametime environment to LDAP for Sametime 8.5.x. Additionally, the vpuserinfo.nsf database contains user data that must be converted because Lotus Sametime uses a different unique identifier for LDAP authentication than with Domino Directory authentication. The unique identifier is used to track user tokens, contact lists, and privacy information.
 

Converting your Sametime environment from Lotus Domino to LDAP authentication

Converting Sametime authentication from Domino Directory to LDAP requires three steps:

1. Enable LDAP on the Domino Directory server
2. Convert Sametime user information in vpuserinfo.nsf to LDAP
3. Reconfigure the Sametime server to use LDAP rather than Domino authentication

For further information, refer to the Sametime Information Center topic, "Replacing the Domino Directory with an LDAP directory."

Enable LDAP on the Domino Directory Server
Each Domino server can easily be converted into an LDAP server. Enabling the Domino server LDAP task serves the Domino directory in LDAP format, which applications can access for authentication or user information lookup. To enable basic LDAP services on the Domino server, perform these steps:

1. Open the Notes.ini file.
2. Locate the ServerTasks line.
3. Add “LDAP” to the end of the line.
4. Restart the Domino server.

This process enables basic LDAP services for the server, which will allow two types of binds, anonymous and authenticated. Preferably, any application binding to the LDAP server should use an authenticated bind to retrieve the full LDAP record. Binding anonymously returns only a subset of information.

Convert the Sametime user information from Domino Directory to LDAP format
The Sametime Name Conversion Utility converts user information from the Domino Directory format to LDAP format. It also performs name manipulation, which is useful when name or organization changes occur after the LDAP conversion. The general process of using the name conversion utility is as follows:

1. Make a backup copy of the vpuserinfo.nsf database.
2. Create the name conversion file.
3. Perform the name conversion process.
4. Test and verify the new vpuserinfo.nsf.
5. Replicate the new vpuserinfo.nsf into your Sametime environment.
   

The conversion from a Domino Directory-based environment to an LDAP-based environment is not trivial. The name conversion process might take several hours, depending on the number and complexity of the directory's entries. Perform a trial run of the conversion before executing it in production. See the Sametime Information Center topic name conversion process for additional information.

To ensure there is sufficient time to complete the conversion in production, IBM recommends taking a snapshot of the vpuserinfo.nsf and converting that copy to LDAP format. Any directory or user changes made after the vpuserinfo.nsf snapshot is taken will not be present after the conversion. This significantly reduces production downtime and reduces risk by allowing administrators to verify a successful conversion before the LDAP vpuserinfo.nsf is rolled into production.

In clustered environments, a single instance of the vpuserinfo.nsf can be taken offline and converted. The converted vpuserinfo.nsf can be copied directly to multiple Sametime servers. It is not necessary to convert each instance of vpuserinfo.nsf if the information in the vpuserinfo.nsf is consistent across the Sametime environment.

To verify proper conversion, install the vpuserinfo.nsf on a Sametime test server running the LDAP directory modules before performing the production migration.

Known issue: Refer to the IBM Support Technote, Sametime name conversion is not working as expected when modifying user names.

Post-conversion user experience: Any directory or user changes made after the vpuserinfo.nsf snapshot was taken will not be present after the conversion. Users logging in initially are prompted that the server contact list has been modified, and they need to select the option to replace the local copy with the server copy. If the user selects any of the other options, vpuserinfo.nsf entry may be overwritten with old data, or the datasets may be merged. If this occurs, ask the user to log off and then replace his vpuserinfo.nsf entry on the server with one from the converted database.

Reconfigure the Sametime Server to use LDAP modules

NOTE: The information in this section supersedes information provided in the Sametime Information Center and Technotes for Sametime 8.5x environments. If you are converting an existing pre-8.5.x Sametime environment from Domino Directory to LDAP, choose LDAP authentication when upgrading to Sametime 8.5.x server. This process has been improved in the Sametime 8.5.1 release, and administrators should note that they can upgrade to Sametime 8.5.1 server first, then convert to LDAP as this section describes.

Each Sametime Community server contains a set of black box modules that are used to interact with the backend directory service. These modules can be configured for Domino Directory or LDAP authentication. To configure the Sametime server to use LDAP modules, follow these steps:

1. Create an LDAPServer document. Instructions on doing this are in Creating an LDAP document in the Configuration database or Step 5 of the Support Technote How to change your Sametime server from Domino to LDAP after installation.
2. Edit the sametime.ini file by locating the "DirectoryType=" line and changing the value from DOMINO to LDAP.
3. Restart the Sametime server.

Enabling optional Sametime features

Lotus Sametime features include options such as Microsoft® Office Integration for Windows® clients, e-mail integration features, and spell check dictionaries. By customizing the embedded Sametime client installation package, administrators can control which of these features are deployed. To do this, administrators must download and extract the Sametime Client Standard package from IBM Passport Advantage, then edit the install.addon.xml file before deploying the install package:

1. Download Part number CZII3ML - IBM Lotus Sametime Standard V8.5.1 Connect Clients Standalone, Notes, Network Installer, Mobile Windows Mac Linux Multilingual, from Passport Advantage. (or CZYF7ML for Sametime 8.5.2)
2. Extract to a local directory (for example 'dir').
3. Edit the \\dir\SametimeStandardClient\sametimeclient.for.notes\Windows\deploy\install.addon.xml file, moving the desired features outside the comment markers:

• all optional features are disabled by default
• any combination of features may be enabled
• make sure to get the entire text between the opening '<' marker and the closing '>' marker when moving features outside the comment markers
• refer to Example install.addon.XML file for further details

Provisioning default preferences

The Administrator can determine the Sametime client preferences, as well as other Notes client settings, that are set by default at install by editing the plugin_customization.ini file. Administrators should note that users can reset these Sametime client preferences (Notes Client > File > Preferences > Sametime) after installation.

Also, existing Notes 8.x client installations cannot be provisioned in this fashion; the existing plugin_customization.ini settings will stay in place. To provision new settings, the Notes client must be uninstalled and reinstalled, or the user's workspace directory deleted, and the install rerun with the new plugin_customizations.ini in place. Deleting the workspace directory is mentioned only for administrators to use during testing; deleting a production user's workspace directory is NOT RECOMMENDED.

The Information Center document Sametime Preferences has a complete Sametime preferences list. Note that the preferences tables are for the Sametime Connect client, though most preferences can be applied to the Sametime embedded client.

Steps for configuring plugin_customization.ini:

1. Download and extract the Notes install package.
2. Edit the \\dir\deploy\plugin_customization.ini.
3. Add the desired Sametime preferences; noting that:

• parameters are case sensitive and consist of three parts: Plug-in name, Attribute, and Value.
• there are three types for Value, namely, Boolean, Integer, or String; for example:

a. Plug-in name: com.ibm.collaboration.realtime.community
b. Attribute: host
c. Value: sametime.com
see sample plugin_customization.ini file available for download here

4. Install and launch the Notes client, and then log into Lotus Sametime, using the embedded Sametime client.
6. Verify that the default Sametime Preferences configured in plugin_customization.ini (Notes Client > File > Preferences > Sametime) were configured.
7. Verify the Notes installation's plugin_customization.ini file settings: Notes Install directory\framework\rcp\plugin_customization.ini.

How should I do it?: Deploying the Sametime add-on installer

Post-installation deployment

Administrators with existing Notes 8.5.1 client installations can run the Sametime add-on installer to upgrade the Sametime client, either locally by running the add-on installer's setup.exe and following the prompts to completion, or with software delivery tools, such as SMS or Altiris:

Local install
The advantage of doing a local installation is that it requires less time; however, keep in mind that it requires workstation administrator rights and user interaction, and that it occupies the workstation. To perform a local installation, follow these steps:

1. Stop the Lotus Notes client.
2. Execute Windows\setup.exe or Windows\SametimeEmbedded.msi to begin installation.
3. Select a language and click Next as needed to proceed through the installation screens.
4. Verify the installation. To validate success for the Sametime client upgrade, in the Notes client menu select Help > About Lotus Notes and click Plug-in Details. The Sametime plug-ins that begin with com.ibm.collaboration.realtime should show the updated client version such as 8.5.0 or 8.5.1, not 8.0.2.

Packaging software such as SMS
The advantages of using packaging software are that it allows the administrator to schedule package rollouts and requires no user interaction. However, it requires workstation administrator rights and depends on the network to deliver files.

To perform an installation using packaging software, follow the documentation provided by the software vendor.

Using Smart Upgrade to deploy the Sametime add-on installer

Lotus Notes Smart Upgrade is a Notes and Domino feature that notifies users of updates available for their Notes client. The Smart Upgrade feature allows administrators to have granular control over which clients receive the upgrade, either through Notes policies or through the configuration of the Smart Upgrade Kit document. The Sametime 8.5.1 add-on installer can also be deployed using Smart Upgrade. This section discusses how to deploy the Sametime add-on installer by using Smart Upgrade, in a chained install with the Notes 8.5.1 FP3 install.

More information on Smart Upgrade can be found in the Using Notes Smart Upgrade section of the Lotus Domino and Notes Information Center. General information on using a chained install can be found in the Support Technote, Chaining Notes Smart Upgrade Kits.

Prerequisites and limitations
Administrators should be aware that:

• The Sametime add-on installer only installs on Lotus Notes Standard 8.5.x client installations. It is not available for the Notes Basic client.
• The targeted workstation must already have the Notes client installed.
• The Notes client must have connectivity to a Domino server.
• The user's Location document must specify the correct home Domino server on the Servers tab.
• Smart Upgrade needs operating-system administrative rights on the workstation.
• The Notes client must be upgraded to no earlier than the Notes 8.5.1 FP3 release.

The Notes Client release number is extremely important when deploying the Sametime add-on installer using Smart Upgrade. Each Lotus Notes installation contains a release number that indicates the Notes version. Smart upgrade compares this string to the release string in the Smart Upgrade Kit document and prompts the user to upgrade, if appropriate. If the Notes release number is not updated, that Notes install is still considered upgradeable, and Smart Upgrade will continue prompting the user.  

Running just the Sametime add-on installer using Smart Upgrade would upgrade the embedded Sametime client, but the Notes release number would stay the same, and Smart Upgrade would continue prompting. Notes/Domino 8.5.2 contains a new feature that allows Smart Upgrade to run the Sametime add-on installer and properly update the Notes client’s release number.

Administrators with pre-8.5.x clients can use the process described in this section to deploy both a Notes upgrade and the Sametime add-on installer in one Smart Upgrade kit by executing a Visual Basic script, which calls both the Notes upgrade and then the Sametime add-on installer.

Each Lotus Notes client version contains a different variant of the Sametime Connect client. The Notes Basic client contains Sametime client code based on the Sametime C++ Toolkits and provides basic functionality. The Notes Standard Client contains code that is exactly the same as the Sametime Connect stand-alone client but packaged so it can install into the Notes client framework. The Sametime add-on installer is applicable only to the Notes Standard Client, as both clients are based on the Lotus Expeditor framework.

Required steps

Step 1. Gather necessary files

1. The Sametime add-on installer available in the Sametime 8.5.x client downloads package or a cumulative fix package, sametime.embedded.add-on.win.exe. For Sametime 8.5.1, the add-on installer can be found in Passport Advantage under part number CZII3ML.
2. A Visual Basic Script chainedinstall.vbs that first calls the 8.5.1 FP3 install, then the Sametime add-on installer. Note that this Visual Basic script is provided as an example but is not supported by IBM.
3. A Notes or Notes Fix Pack install from Notes Support & Downloads or IBM Fix Central. Make sure the download package is for Notes "Standard", not Notes Basic. The package Notes_851FP3_Standard_W32.exe is used for this example.
4. The Windows Visual Basic script launcher cscript.exe. Smart Upgrade uses cscript.exe to launch the VB script. In a default Windows operating-system installation, it is located in the windows\system32 folder.
   

Step 2. Create network share folder

1. Create a folder (NETWORKSHARE, for this example) and share it on the network so it's visible to both the Smart Upgrade Domino server and the Notes client machines to be upgraded. The Domino server and targeted workstation/user must be able to access the share without being prompted to authenticate.
2. Under NETWORKSHARE, create two additional folders:

• 851FP3 for this example
• ST851ADDON for this example

Step 3. Copy cscript.exe to NETWORKSHARE

Step 4.  Extract Notes install and Sametime add-on installer files to NETWORKSHARE
a. Run and unpack the Notes install file (see figure 2). Use the second, lower option “save to a specific location," enter the path to NETWORKSHARE\NOTES851, and click OK. Cancel out of the Notes install when it begins.

Figure 2. Extracted Notes 8.5.1 FP3 install files


b. Repeat step 1, for the Sametime add-on installer executable, saving it to NETWORKSHARE\ST851 (see figure 3).

Figure 3. Extracted Sametime 8.5.1 install files


NOTE: Do not remove these files after they have been extracted. Smart Upgrade uses these files for the install.

Step 5.  Customize the chainedinstall.vbs file
a. Locate and edit the two strInstallPackagePath statements below in the chainedinstall.vbs file, to correctly map to the setup.exe files for the Notes install and the Sametime add-on installer, replacing "server" with the fully qualified name of the server hosting the network share:

Const strInstallPackagePath_1 = "\\server\NETWORKSHARE\NOTES851\AllClient.msi.w32.fixpack\setup.exe"
Const strInstallPackagePath_2 = "\\server\NETWORKSHARE\ST851ADDON\setup.exe"

b. Locate and edit the two strInstallPackagName statements in the chainedinstall.vbs file to these values:

Const strInstallPackageName_1 = "Notes 8.5.1 FP3"
Const strInstallPackagename_2 = "Sametime 8.5"

The strInstallPackageName parameters change between Notes and Sametime versions. In the example above, the Notes 8.5.1 FP3 update and Sametime 8.5 updates are being installed. If the deployment package were Sametime 8.5.1, the string would be "Sametime 8.5.1".

NOTE: In the chainedinstall.vbs file, the InstallShield  /s (silent) parameter is used. Also, the Microsoft installer /qb (silent) option is used:

strSetupCmd_1 = strInstallPackagePath_1 & " /s /v" & chr(34)&"/l*v " & LogDir &"notes_install.txt /qb!" & chr(34)
strSetupCmd_2 = strInstallPackagePath_2 & " /s /v" & chr(34)&"/qb /liwae " & LogDir & "sametime_install.txt" & chr(34)

Step 6. Copy the customized chainedinstall.vbs to NETWORKSHARE

Step 7. Create the Smart Upgrade Kit
Follow the instructions in the Lotus Domino and Notes Information Center to create a Kit document in the Smart Upgrade application as shown in figure 4. Documentation on Smart Upgrade Kit documents can be found under the section Using Notes Smart Upgrade.

Different Smart Upgrade kits must be created, depending on the type of client package that was used for deployment. A majority of end users might have the Notes-client-only install, but IT departments and administrators may have the All Client package containing Lotus Domino Designer and the Domino Administrator client. Thus be sure to specify the path to the cscript.exe and chainedinstall.vbs files (see figure 4).

Figure 4. Smart Upgrade Kit document


The approach here is to execute the cscript.exe application and pass in the chainedinstall.vbs script as a parameter. This first runs the upgrade of the Notes client followed by an install of the Sametime add-on package. The upgrade kit configuration also must specify the source version to which the upgrade will be applied. In the example above in figure 4, the update applies only to Lotus Notes 8.5.1 clients; however, wildcards and pattern matching can also be used. Multiple source versions can be listed in the space provided, one per line.

Step 8. Validate the install
When the Smart Upgrade kit is enabled, Notes clients that match the specified source version, source configuration, and install type settings in the the Smart Upgrade Kit document will be prompted that there is an upgrade available. If the user accepts the upgrade, Lotus Notes will exit, and the user will see pop-up dialogs regarding the installation. There will be a slight delay, depending on network speed, as the client downloads and installs the updates.

To validate success for the Notes client upgrade, in the Notes client menu, select Help > About Lotus Notes. It should show the updated Notes client. In the example above, this will be release 8.5.1 FP3.

To validate success for the Sametime client upgrade, in the Notes client menu, select Help > About Lotus Notes, and click Plug-in Details. The Sametime plug-ins that begin with com.ibm.collaboration.realtime should show the updated client version, for example, 8.5.0 and not 8.0.2.

Troubleshooting

To troubleshoot the Smart Upgrade process, review the following log files for any exceptions:

• smartupgrade.log, which is the Notes Smart Upgrade log, used to troubleshoot Smart Upgrade issues
• LotusInstall.log, the Notes Fix Pack installer log

Both of the files are located in the C:\Documents and Settings\user folder.

Resources

Smart Upgrade reference links:

IBM Lotus Domino and Notes Information Center - How Smart Upgrade performs an upgrade
IBM Lotus Domino and Notes Information Center - Using Notes Smart Upgrade

General references:
Deploying the Sametime client to users
Lotus Sametime Wiki
Lotus Sametime Support

About the authors

This article is a collaboration among the following individuals and teams within IBM Lotus software: James Pappas of the Sametime Development team, Thinh M Hoang from the Sametime Support team, Andy Yiu of IBM Software Services for Lotus (ISSL), and Clint Reams of the Accelerated Value Program.